fix(lessons): theory shows what the terminal prints, checked by a permanent replay (THI-353) by thierryvm · Pull Request #391 · thierryvm/TerminalLearning

thierryvm · 2026-09-24T12:35:49Z

Why

Exercises are fixed (#389, #390); the lesson theory still showed output the terminal does not print — a beginner who types the example sees something else. THI-353.

What

Permanent replay of the theory — src/test/lessonTheory.test.ts replays every terminal session shown in a lesson code block through the engine, from the lesson's own starting state (Exercise.setup), in linux / macos / windows, and compares with the lesson text. 754 commands replayed; 390 match.
- Remaining gaps are a shrink-only ratchet (lessonTheoryGaps.ts, 174 entries — mostly advanced Git/GitHub lessons whose starting state lacks the history their theory shows, plus gh and background jobs not simulated yet). A new gap fails; a fixed gap fails until its entry is removed.
- BASH_SHOWN_ON_WINDOWS_MAX = 39: lessons whose code blocks show bash to a Windows learner. Can only go down.
13 lesson examples corrected: ls -l (time, byte sizes), ls -a (.zshrc), grep -n (line 6), wc (6 22 143), permissions listing, chmod/chown sizes, apt (noble), 2> example, Windows ping TTL.
One block per environment for the PATH and git init lessons (was: bash and PowerShell shown side by side to everyone); PATH warning gets a PowerShell variant ($PROFILE).
Engine: ls -l size = content bytes (same as wc -c); $env:X = "…$env:Y…" expands in double quotes, literal in single quotes; git init prints C:/Users/user/… on Windows like Git for Windows.
CHANGELOG + STORY: catch-up for fix(terminal): a real shell layer — lists, pipelines and redirections (THI-353) #389/fix(terminal): print what a real shell prints — pwd, cd -, export, ls, wc, apt (THI-353) #390 (were missing) + this PR.

Found on the way (next PR)

mv documents/notes.txt . replaces the home directory with the file; cp file dir / Move-Item file dir overwrite the directory; mv -i treats -i as a path. Dedicated fix next.

Gates

test-runner: type-check ✅ lint ✅ build ✅ — 2646 passed / 0 failed (20 env-gated Supabase integration skips)
curriculum-validator: 0 CRITICAL
feature-dev:code-reviewer: no finding ≥ 80 (noted: substring fallback in the replay matcher is lenient — to harden later)
Chrome (local): Windows PATH lesson and git init lesson — typed the theory commands, terminal output identical to the lesson

🤖 Generated with Claude Code

Résumé par Sourcery

Faire en sorte que la théorie des leçons reflète fidèlement la sortie du terminal et vérifier en continu cette correspondance sous Linux, macOS et Windows.

Corrections de bugs :

Corriger les exemples des leçons afin que la sortie du terminal affichée corresponde au simulateur dans les environnements pris en charge.
Corriger la sortie spécifique à l’environnement pour Git sous Windows et l’expansion des variables dans PowerShell.

Améliorations :

Ajouter une relecture multiplateforme permanente qui vérifie les sessions de terminal des leçons par rapport au texte des leçons et suit les divergences restantes à l’aide d’une liste d’écarts qui ne peut que diminuer.
Afficher des exemples de PATH et de git-init spécifiques à l’environnement au lieu de présenter simultanément des variantes de shell incompatibles.
Aligner la sortie du terminal, notamment les tailles de fichiers, les horodatages, les fichiers cachés, le nombre de caractères, les permissions, les sources de paquets, les listes issues de redirections et les détails de ping sous Windows, sur le contenu des leçons.

Documentation :

Documenter dans le journal des modifications et l’historique du projet les améliorations de fidélité entre la théorie et la sortie, la couverture de la vérification et les écarts connus restants.

Tests :

Ajouter une couverture de régression pour la relecture des leçons, les chemins Git sous Windows, l’expansion des variables d’environnement dans PowerShell et les tailles de fichiers ls calculées dynamiquement.

Original summary in English

Summary by Sourcery

Make lesson theory faithfully reflect terminal output and continuously verify that alignment across Linux, macOS, and Windows.

Bug Fixes:

Correct lesson examples so their displayed terminal output matches the simulator across supported environments.
Fix environment-specific output for Git on Windows and PowerShell variable expansion.

Enhancements:

Add a permanent cross-platform replay that verifies lesson terminal sessions against the lesson text and tracks remaining mismatches with a shrink-only gap list.
Show environment-specific PATH and git-init examples instead of presenting incompatible shell variants together.
Align terminal output such as file sizes, timestamps, hidden files, text counts, permissions, package sources, redirection listings, and Windows ping details with the lesson content.

Documentation:

Document the theory-output fidelity improvements, verification coverage, and remaining known gaps in the changelog and project story.

Tests:

Add regression coverage for lesson replay, Windows Git paths, PowerShell environment expansion, and dynamically calculated ls file sizes.

…manent replay (THI-353) - Replay every terminal session shown in a lesson code block through the engine, from the lesson's starting state, in each environment (src/test/lessonTheory.test.ts). Known gaps are a shrink-only ratchet (lessonTheoryGaps.ts, 174 entries), plus a ceiling on lessons that show bash to Windows learners (39). - Fix 13 lesson examples whose output did not match (ls -l, ls -a, grep -n, wc, chmod, chown, apt, stderr, Windows ping) and give the PATH and git init lessons a single block per environment. - ls -l size comes from the content bytes, like wc -c. - $env:X = "..." expands $env:Y inside double quotes (PowerShell). - git init prints C:/Users/user/... on Windows, like Git for Windows. - CHANGELOG and STORY: catch up #389 and #390, add this change. Co-Authored-By: Claude Opus 5.5 <[email protected]>

sourcery-ai

Sorry @thierryvm, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 5 hours by commenting @sourcery-ai review. Upgrade to get a review now.

vercel · 2026-09-24T12:35:55Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
terminal-learning	Ready	Preview	Sep 24, 2026 12:36pm UTC

sourcery-ai · 2026-09-24T12:36:20Z

Guide du réviseur

Cette PR rend la théorie des leçons exécutable et vérifiée en continu : elle rejoue 754 commandes de terminal depuis les états initiaux des leçons dans tous les environnements pris en charge, corrige les transcriptions de cursus incohérentes, aligne le comportement du moteur sur ces transcriptions et utilise un mécanisme de suivi des écarts qui ne peut que se réduire afin d’éviter les régressions de fidélité.

Diagramme de séquence pour le rejeu permanent de la théorie des leçons

sequenceDiagram
    participant Test as lessonTheory.test
    participant Lesson as Lesson curriculum
    participant Setup as Exercise.setup
    participant Engine as terminalEngine
    participant Gaps as lessonTheoryGaps

    Test->>Lesson: Lire les blocs de code du terminal
    Test->>Setup: Créer l’état initial de la leçon
    Setup-->>Test: Renvoyer TerminalState
    loop Linux, macOS, Windows
        Test->>Engine: Rejouer les commandes de la leçon
        Engine-->>Test: Renvoyer la sortie du terminal
        Test->>Test: Comparer la sortie avec le texte de la leçon
    end
    Test->>Gaps: Vérifier les commandes non correspondantes
    Gaps-->>Test: Autoriser uniquement les écarts existants
    Test-->>Test: Échouer en cas de nouveaux écarts ou d’entrées non corrigées

Modifications au niveau des fichiers

Modification	Détails	Fichiers
Ajout d’un test permanent de rejeu inter-environnements qui valide les transcriptions de terminal des leçons par rapport au moteur et impose un suivi qui ne peut que se réduire pour les exemples non pris en charge.	Rejoue les sessions des blocs de code depuis l’état `Exercise.setup` de chaque leçon sous Linux, macOS et Windows. Normalise les invites, les commentaires, la sortie et les erreurs intentionnelles avant de comparer la sortie affichée et la sortie réelle. Échoue en cas de nouvelles incohérences, exige la suppression des écarts connus résolus et limite les exemples propres à bash affichés sous Windows. Répertorie les écarts restants, principalement liés à l’état avancé de Git/GitHub, aux commandes non prises en charge, aux sorties illustratives et aux tâches en arrière-plan.	`src/test/lessonTheory.test.ts` `src/test/lessonTheoryGaps.ts`
Correction des exemples de théorie des leçons et mise en conformité des blocs spécifiques aux environnements avec le comportement réel du terminal.	Mise à jour des sorties pour les exemples `ls`, `grep`, `wc`, les permissions, `apt`, la redirection et `ping` sous Windows. Unification des exemples de PATH et de `git init` dans des blocs spécifiques aux environnements, avec notamment un avertissement PowerShell concernant `$PROFILE`. Documentation du travail sur la fidélité de la théorie et des corrections précédentes dans le journal des modifications et l’histoire du projet.	`src/app/data/curriculum.ts` `CHANGELOG.md` `STORY.md`
Alignement de la sortie du moteur sur la théorie corrigée pour les tailles de fichiers, l’expansion de l’environnement PowerShell et les chemins Git sous Windows.	Calcul de la taille des fichiers de `ls -l` à partir du nombre actuel d’octets du contenu. Expansion des variables d’environnement dans les affectations PowerShell entre guillemets doubles, tout en préservant les littéraux entre guillemets simples. Formatage des chemins d’initialisation de Git pour Windows avec `C:/` et des barres obliques.	`src/app/data/terminalEngine.ts` `src/app/data/commands/git.ts`
Ajout de tests de régression ciblés du moteur pour les nouvelles sémantiques de sortie corrigées.	Vérification du formatage des chemins de `git init` sous Windows et de la sortie lors de la réinitialisation. Vérification de l’expansion lors de l’affectation de PATH dans PowerShell. Vérification du nombre d’octets de `ls -l` par rapport au comportement de `wc` et au contenu mis à jour des fichiers.	`src/test/terminalEngine.test.ts`

Conseils et commandes

Interagir avec Sourcery

Déclencher une nouvelle revue : Commentez @sourcery-ai review sur la pull request.
Poursuivre les discussions : Répondez directement aux commentaires de revue de Sourcery.
Générer une issue GitHub à partir d’un commentaire de revue : Demandez à Sourcery de créer une issue à partir d’un commentaire de revue en y répondant. Vous pouvez également répondre à un commentaire de revue avec @sourcery-ai issue pour créer une issue à partir de celui-ci.
Générer un titre de pull request : Écrivez @sourcery-ai n’importe où dans le titre de la pull request pour générer un titre à tout moment. Vous pouvez également commenter @sourcery-ai title sur la pull request pour générer à nouveau le titre à tout moment.
Générer un résumé de pull request : Écrivez @sourcery-ai summary n’importe où dans le corps de la pull request pour générer un résumé de PR à tout moment, exactement à l’endroit souhaité. Vous pouvez également commenter @sourcery-ai summary sur la pull request pour générer à nouveau le résumé à tout moment.
Générer le guide du réviseur : Commentez @sourcery-ai guide sur la pull request pour générer à nouveau le guide du réviseur à tout moment.
Résoudre tous les commentaires de Sourcery : Commentez @sourcery-ai resolve sur la pull request pour résoudre tous les commentaires de Sourcery. Cette commande est utile si vous avez déjà traité tous les commentaires et ne souhaitez plus les voir.
Ignorer toutes les revues de Sourcery : Commentez @sourcery-ai dismiss sur la pull request pour ignorer toutes les revues existantes de Sourcery. Particulièrement utile si vous souhaitez recommencer une nouvelle revue : n’oubliez pas de commenter @sourcery-ai review pour déclencher une nouvelle revue !

Personnaliser votre expérience

Accédez à votre tableau de bord pour :

Activer ou désactiver des fonctionnalités de revue, telles que le résumé de pull request généré par Sourcery, le guide du réviseur, etc.
Modifier la langue de la revue.
Ajouter, supprimer ou modifier les instructions de revue personnalisées.
Ajuster les autres paramètres de revue.

Obtenir de l’aide

Contactez notre équipe d’assistance pour toute question ou tout commentaire.
Consultez notre documentation pour obtenir des guides et des informations détaillés.
Restez en contact avec l’équipe Sourcery en nous suivant sur X/Twitter, LinkedIn ou GitHub.

Original review guide in English

Reviewer's Guide

This PR makes lesson theory executable and continuously checked: it replays 754 terminal commands from lesson starting states across all supported environments, corrects mismatched curriculum transcripts, aligns engine behavior with those transcripts, and uses a shrink-only gap ratchet to prevent fidelity regressions.

Sequence diagram for permanent lesson theory replay

sequenceDiagram
    participant Test as lessonTheory.test
    participant Lesson as Lesson curriculum
    participant Setup as Exercise.setup
    participant Engine as terminalEngine
    participant Gaps as lessonTheoryGaps

    Test->>Lesson: Read terminal code blocks
    Test->>Setup: Create lesson starting state
    Setup-->>Test: Return TerminalState
    loop Linux, macOS, Windows
        Test->>Engine: Replay lesson commands
        Engine-->>Test: Return terminal output
        Test->>Test: Compare output with lesson text
    end
    Test->>Gaps: Check unmatched commands
    Gaps-->>Test: Allow only existing gaps
    Test-->>Test: Fail on new gaps or unfixed gap entries

File-Level Changes

Change	Details	Files
Added a permanent cross-environment replay test that validates lesson terminal transcripts against the engine and enforces shrink-only tracking for unsupported examples.	Replays code-block sessions from each lesson’s Exercise.setup state on Linux, macOS, and Windows. Normalizes prompts, comments, output, and intentional errors before comparing displayed and actual output. Fails on newly introduced mismatches, requires resolved known gaps to be removed, and caps bash-only examples shown on Windows. Catalogs remaining gaps, primarily advanced Git/GitHub state, unsupported commands, illustrative output, and background jobs.	`src/test/lessonTheory.test.ts` `src/test/lessonTheoryGaps.ts`
Corrected lesson theory examples and made environment-specific blocks accurately reflect terminal behavior.	Updated outputs for ls, grep, wc, permissions, apt, redirection, and Windows ping examples. Unified PATH and git init examples into environment-specific blocks, including a PowerShell $PROFILE warning. Documented the theory-fidelity work and prior fixes in the changelog and project story.	`src/app/data/curriculum.ts` `CHANGELOG.md` `STORY.md`
Aligned engine output with the corrected theory for file sizes, PowerShell environment expansion, and Windows Git paths.	Computes ls -l file sizes from current content bytes. Expands environment variables in double-quoted PowerShell assignments while preserving single-quoted literals. Formats Git for Windows initialization paths with C:/ and forward slashes.	`src/app/data/terminalEngine.ts` `src/app/data/commands/git.ts`
Added focused engine regression tests for the newly corrected output semantics.	Verifies Windows git init path formatting and reinitialization output. Checks PowerShell PATH assignment expansion. Checks ls -l byte counts against wc behavior and updated file contents.	`src/test/terminalEngine.test.ts`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

sourcery-ai Bot reviewed Sep 24, 2026

View reviewed changes

vercel Bot deployed to Preview September 24, 2026 12:36 View deployment

thierryvm merged commit b96c016 into main Sep 24, 2026
4 checks passed

thierryvm mentioned this pull request Sep 24, 2026

fix(terminal): cp/mv into a directory, and Windows paths PowerShell accepts (THI-353) #392

Merged

Navigation Menu

fix(lessons): theory shows what the terminal prints, checked by a permanent replay (THI-353) - #391

fix(lessons): theory shows what the terminal prints, checked by a permanent replay (THI-353)#391
thierryvm merged 1 commit into
mainfrom
fix/thi-353-theory-content

thierryvm commented Sep 24, 2026 •

edited by sourcery-ai Bot

Loading

Uh oh!

sourcery-ai Bot left a comment

Uh oh!

vercel Bot commented Sep 24, 2026 •

edited

Loading

Uh oh!

sourcery-ai Bot commented Sep 24, 2026

Interagir avec Sourcery

Personnaliser votre expérience

Obtenir de l’aide

Reviewer's Guide

Sequence diagram for permanent lesson theory replay

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

thierryvm commented Sep 24, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

Found on the way (next PR)

Gates

Résumé par Sourcery

Summary by Sourcery

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

vercel Bot commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sourcery-ai Bot commented Sep 24, 2026

Guide du réviseur

Diagramme de séquence pour le rejeu permanent de la théorie des leçons

Modifications au niveau des fichiers

Interagir avec Sourcery

Personnaliser votre expérience

Obtenir de l’aide

Reviewer's Guide

Sequence diagram for permanent lesson theory replay

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

thierryvm commented Sep 24, 2026 •

edited by sourcery-ai Bot

Loading

vercel Bot commented Sep 24, 2026 •

edited

Loading